Start documentation section for Butterfly #460
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
✅ Deploy Preview for openrefine-website ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Member
Author
|
@Abbe98, @sunilnatraj, since both of you have worked on extensions, would you mind reading over this new bit of Butterfly documentation? I'd be interested in hearing if you find it useful, and/or if anything else would be useful to include here. |
tfmorris
requested changes
Jan 16, 2026
Member
tfmorris
left a comment
tfmorris
left a comment
There was a problem hiding this comment.
I just discovered these six month old comments from a review that I never submitted. Sorry!
The comment about "non-obvious conceptual stuff" probably needs expansion/explanation, but I'm going to submit this without further edits so it doesn't get pushed down on the stack again.
| different architecture, where data is stored on disk by default and cached in memory if the project is small enough. | ||
|
|
||
| ### Butterfly {#butterfly} | ||
| The functional extensibility of OpenRefine is provided by a fork of the [SIMILE Butterfly](https://github.com/OpenRefine/simile-butterfly) modular web application framework. With this framework, extensions are able to provide new functionality both in the |
Member
There was a problem hiding this comment.
Suggested change
| The functional extensibility of OpenRefine is provided by a fork of the [SIMILE Butterfly](https://github.com/OpenRefine/simile-butterfly) modular web application framework. With this framework, extensions are able to provide new functionality both in the | |
| The functional extensibility of OpenRefine is provided by a fork of the [MIT SIMILE Butterfly](https://github.com/OpenRefine/simile-butterfly) modular web application framework. With this framework, extensions are able to provide new functionality both in the |
| The functional extensibility of OpenRefine is provided by a fork of the [SIMILE Butterfly](https://github.com/OpenRefine/simile-butterfly) modular web application framework. With this framework, extensions are able to provide new functionality both in the | ||
| server- and client-side. A [list of known extensions](https://openrefine.org/extensions) is maintained on our website and we have [specific documentation for extension developers](technical-reference/writing-extensions.md). | ||
|
|
||
| Butterfly organizes back-end functionality using a collection of modules. The only module exposed by OpenRefine is the `core` module, which provides extension points for other modules to hook into. |
Member
There was a problem hiding this comment.
Suggested change
| Butterfly organizes back-end functionality using a collection of modules. The only module exposed by OpenRefine is the `core` module, which provides extension points for other modules to hook into. | |
| Butterfly organizes back-end functionality using a collection of modules. The only module exposed by core OpenRefine (not including the bundled extensions) is the `core` module, which provides extension points for other modules to hook into. Butterfly modules can declare their dependencies using the `requires=` property in the `module/MOD-INFO/module.properties file. |
|
|
||
| Butterfly organizes back-end functionality using a collection of modules. The only module exposed by OpenRefine is the `core` module, which provides extension points for other modules to hook into. | ||
|
|
||
| Each module uses a JavaScript file named `controller.js` to connect different parts of the backend. Butterfly uses a JavaScript interpreter to run this and other provided JavaScript files to configure the back-end. Extensions rely on `controller.js`, and specifically an `init` method within that file, to leverage the aforementioned extension points. |
Member
There was a problem hiding this comment.
Probably worth explaining how the Javascript/Java "glue" works here (or at least point to the extension docs).
More generally some of the non-obvious conceptual stuff should receive a significant portion of the attention.
|
|
||
| Each module uses a JavaScript file named `controller.js` to connect different parts of the backend. Butterfly uses a JavaScript interpreter to run this and other provided JavaScript files to configure the back-end. Extensions rely on `controller.js`, and specifically an `init` method within that file, to leverage the aforementioned extension points. | ||
|
|
||
| While Butterfly does allow for modules to manage their own API endpoints, extension modules typically register their endpoints through the form of commands. HTTP requests for those commands are then dispatched by the `core` module. |
Member
There was a problem hiding this comment.
True for HTTP commands, but there are many other extension registries for importers, exporters, GREL functions, etc.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
As I learn more about OpenRefine's codebase, I figured I could contribute a little bit of what I've learned about Butterfly to the documentation. I've been trying to figure out an appropriate scope for an initial section on Butterfly (e.g. is it worthwhile to go into how request routing works?) but in the end decided to provide a small starting point and get feedback from others on where additional documentation might be helpful.